home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / comm / mnpc12.zip / MNPC.DOC < prev    next >
Text File  |  1987-11-30  |  17KB  |  482 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.      
  8.      
  9.      
  10.      
  11.      
  12.                          The Microcom MNP Library
  13.                           (Microsoft C Version)
  14.      
  15.      
  16.      
  17.                            PROGRAMMER'S MANUAL
  18.      
  19.      
  20.      
  21.      
  22.      
  23.      
  24.      
  25.      
  26.      
  27.      
  28.      
  29.      
  30.      
  31.      
  32.                                 Version 1.0
  33.      
  34.                              December 15, 1987
  35.      
  36.      
  37.      
  38.      
  39.      
  40.      
  41.      
  42.      
  43.      
  44.      
  45.      
  46.      
  47.      
  48.      
  49.      
  50.      
  51.      
  52.      
  53.      
  54.      
  55.      
  56.      
  57.      
  58.                               Microcom, Inc.
  59.                           1400 Providence Highway
  60.                             Norwood, MA 02062
  61.  
  62.  
  63.  
  64.  
  65.  
  66.      
  67.      
  68.      The Microcom MNP Library and MNP are trademarks of Microcom, Inc.
  69.      Microsoft and MS-DOS are trademarks of Microsoft Corporation.  
  70.      IBM is a registered trademark of International Business Machines.
  71.      
  72.      
  73.      This manual is not subject to copyright and may be freely copied.
  74.      
  75.      
  76.      
  77.      
  78.      
  79.      
  80.      
  81.      
  82.      
  83.      
  84.      
  85.      
  86.      
  87.      
  88.      
  89.      
  90.      
  91.      
  92.      
  93.      
  94.      
  95.      
  96.      
  97.      
  98.      
  99.      
  100.      
  101.      
  102.      
  103.      
  104.      
  105.      
  106.      
  107.      
  108.      
  109.      
  110.      Questions relating to the Microcom MNP Library should be directed to
  111.      Microcom at:
  112.      
  113.                               Microcom, Inc.
  114.                        15303 Ventura Blvd., Suite 900
  115.                           Sherman Oaks, CA 91403
  116.                                (818)986-4212
  117.  
  118.  
  119.  
  120.  
  121.  
  122.      
  123.      1. INTRODUCTION
  124.      
  125.           The Microcom MNP Library is a set of subroutines which implement the
  126.      stream mode of the link protocol in Microcom Networking Protocol (MNP).
  127.      This mode of the MNP link protocol is appropriate for interworking with MNP
  128.      error-correcting modems or with other software implementations which use
  129.      the Microcom MNP Library or other compatible software.
  130.      
  131.           This version of the library provides a set of C and assembly
  132.      language routines which are designed to be easily integrated into an
  133.      application program written in C and compiled using the Microsoft C
  134.      compiler (version 4.0).  Through the use of these routines, an
  135.      application is able to perform error-free data communications over a
  136.      physical-connection, such as one established on the public switched
  137.      telephone network.
  138.      
  139.           These MNP Library subroutines are especially for the IBM Personal
  140.      Computer family (and compatibles) under PCDOS (MS-DOS).  Hardware
  141.      facilities for asynchronous communications are required.
  142.  
  143.  
  144.  
  145.  
  146.  
  147.      2. LIBRARY MODULES
  148.      
  149.           The Microcom MNP LIbrary is supplied in one of two forms, object
  150.      library only and object library with source.  The source version is de-
  151.      scribed in more detail in a file ('readme.doc') supplied as part of the
  152.      source version distribution.
  153.      
  154.           In the case of the object library only form, the distribution diskette
  155.      contains one file, mnp.lib, which includes the various object modules
  156.      which make up the MNP Library.
  157.      
  158.           When building the executable form of a particular application, the
  159.      mnp.lib file should be specified if the application calls any MNP sub-
  160.      routine described in this document.  The manner in which library modules
  161.      are specified for inclusion varies according to the linkage editor
  162.      employed in building the application program run module.
  163.  
  164.  
  165.  
  166.  
  167.  
  168.      3. LINK MANAGEMENT
  169.      
  170.           In general, the MNP link follows the life of the normal physical-
  171.      connection.  Immediately after the physical-connection is made (e.g. after
  172.      a modem first reports carrier detected), the application must attempt the
  173.      establishment of the Link via the MNPCONNECT subroutine.  MNP-capable
  174.      modems which answer the incoming telephone call, for example, must receive
  175.      the Link establishment sequence within 4 seconds of physical-connection
  176.      establishment.  If a link is not attempted within this period, such modems
  177.      may fall back to a normal connection and it will not be possible to provide
  178.      a reliable connection on that particular call.
  179.      
  180.           Link termination, performed via the MNPDISCONNECT call, should
  181.      immediately precede termination of the physical-connection, i.e. right
  182.      before hanging up the telephone.  Note that the Link is active for the
  183.      entire duration of the physical-connection.
  184.      
  185.           During the data phase of the Link (i.e. after establishment but before
  186.      termination), the Link must be kept running by allowing the Link code to
  187.      execute periodically.  Any of the data phase calls, namely MNPSEND,
  188.      MNPRECEIVE, MNPSTATUS, and MNPBREAK, will accomplish this.  One of these
  189.      routines must be called every 250ms or so which means that the Link code
  190.      gets a chance to run about 4 times per second.  The absolute interval is
  191.      not critical and it may be possible to reduce the frequency as well and
  192.      still get reasonable performance.  Polling the Link code, however, must
  193.      occur with a predictable frequency otherwise the Link may be lost.  When
  194.      the Link is lost, an MNP error-correcting modem may clear the call.
  195.      
  196.           When a Link is in progress, all line I/O is performed via the
  197.      appropriate MNP call rather than by using other C mechanisms.  It 
  198.      may be the case, however, that the com port opened elsewhere in the
  199.      application, must remain open.
  200.      
  201.           Data sent and received on the Link will be "chunked" depending on the
  202.      number of bytes which happen to be sent in a single data message.  The
  203.      maximum amount in a single message is 64 bytes.  This "chunking" is not
  204.      noticeable to the sender but can be perceived by the data receiver.
  205.      Strings of data may be split over more than one data message and some
  206.      messages may have to be sent more than once when there is noise on the
  207.      connection.  Retransmission can be seen by the application as an
  208.      interruption, possibly in the middle of some data string.  The application
  209.      should be examined to see if there are any cases involving timing
  210.      dependencies which could be adversely effected by this kind of 
  211.      irregularity in the data flow.
  212.  
  213.  
  214.  
  215.  
  216.  
  217.      4. LINK INTERFACE SUBROUTINES
  218.      
  219.      4.1  Link Establishment - MNPCONNECT
  220.      
  221.           MNPCONNECT is used to establish a Link.  It is called after the
  222.      physical-connection has been established.  It can take up to 5 seconds
  223.      for an MNPCONNECT call to complete.
  224.      
  225.           MNPCONNECT has the following parameters:
  226.      
  227.                RATE - an integer which indicates the speed of the
  228.                       physical-connection, as follows:
  229.      
  230.                           1 = 110 bps
  231.                           2 = 300 bps
  232.                           4 = 1200 bps
  233.                           5 = 2400 bps
  234.      
  235.                       [Note: Other speeds are not supported in this
  236.                        version of the Microcom MNP Library.]
  237.      
  238.                FORMAT - an integer which indicates the data format,
  239.                         as follows:
  240.      
  241.                          0 = 8 data bits, no parity
  242.                          1 = 7 data bits, even parity
  243.                          2 = 7 data bits, odd parity
  244.                          3 = 7 data bits, mark parity
  245.                          4 = 7 data bits, space parity
  246.      
  247.                       [Note: In this Library version, once the Link
  248.                        is established, it is not possible to change
  249.                        format.]
  250.      
  251.                PORT -  an integer which indicates the communications
  252.                        port, as follows:
  253.      
  254.                          1 = COM1
  255.                          2 = COM2
  256.      
  257.                       [Note: This Library version does not support
  258.                        other comm ports.  Also, COM2 cannot be speci-
  259.